
/*
 * Copyright 2002-2019 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/*
 *版权所有2002-2019原作者。
 *
 *根据Apache许可证2.0版（“许可证”）获得许可；
 *除非符合许可证，否则不得使用此文件。
 *您可以在以下地址获取许可证副本：
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 *除非适用法律要求或书面同意，软件
 *根据许可证分发的内容是按“原样”分发的，
 *无任何明示或暗示的保证或条件。
 *有关管理权限和
 *许可证下的限制。
 */

package org.springframework.beans.factory.config;

import java.util.Properties;

import org.springframework.beans.factory.FactoryBean;
import org.springframework.beans.factory.InitializingBean;
import org.springframework.core.CollectionFactory;
import org.springframework.lang.Nullable;

/**
 * Factory for {@link java.util.Properties} that reads from a YAML source,
 * exposing a flat structure of String property values.
 *
 * <p>YAML is a nice human-readable format for configuration, and it has some
 * useful hierarchical properties. It's more or less a superset of JSON, so it
 * has a lot of similar features.
 *
 * <p><b>Note: All exposed values are of type {@code String}</b> for access through
 * the common {@link Properties#getProperty} method (e.g. in configuration property
 * resolution through {@link PropertyResourceConfigurer#setProperties(Properties)}).
 * If this is not desirable, use {@link YamlMapFactoryBean} instead.
 *
 * <p>The Properties created by this factory have nested paths for hierarchical
 * objects, so for instance this YAML
 *
 * <pre class="code">
 * environments:
 *   dev:
 *     url: https://dev.bar.com
 *     name: Developer Setup
 *   prod:
 *     url: https://foo.bar.com
 *     name: My Cool App
 * </pre>
 *
 * is transformed into these properties:
 *
 * <pre class="code">
 * environments.dev.url=https://dev.bar.com
 * environments.dev.name=Developer Setup
 * environments.prod.url=https://foo.bar.com
 * environments.prod.name=My Cool App
 * </pre>
 *
 * Lists are split as property keys with <code>[]</code> dereferencers, for
 * example this YAML:
 *
 * <pre class="code">
 * servers:
 * - dev.bar.com
 * - foo.bar.com
 * </pre>
 *
 * becomes properties like this:
 *
 * <pre class="code">
 * servers[0]=dev.bar.com
 * servers[1]=foo.bar.com
 * </pre>
 *
 * <p>Requires SnakeYAML 1.18 or higher, as of Spring Framework 5.0.6.
 *
 * @author Dave Syer
 * @author Stephane Nicoll
 * @author Juergen Hoeller
 * @since 4.1
 */
/**
 *从YAML源读取的{@link java.util.财产工厂，
 *显示String属性值的平面结构。
 *
 *＜p＞YAML是一种很好的人类可读的配置格式，它有一些
 *有用的分层财产。它或多或少是JSON的超集，因此
 *有很多相似的特征。
 *
 *<p><b>注意：所有公开的值都是｛@code String｝</b>类型，以便通过
 *通用的{@link财产#getProperty}方法（例如在配置属性中
 *通过{@link PropertyResourceConfigurer#setProperties（财产）}进行解析。
 *如果这不可取，请改用｛@link YamlMapFactoryBean｝。
 *
 *<p>此工厂创建的财产具有层次结构的嵌套路径
 *对象，因此例如此YAML
 *
 *<pre-class=“code”>
 *环境：
 *设备：
 *网址：https://dev.bar.com
 *name:开发人员设置
 *产品：
 *网址：https://foo.bar.com
 *name:我的酷应用
 *</pre>
 *
 *转化为这些财产：
 *
 *<pre-class=“code”>
 *环境.dev.url=https://dev.bar.com
 *environments.dev.name=开发人员设置
 *环境.prod.url=https://foo.bar.com
 *environment.prod.name=我的酷应用程序
 *</pre>
 *
 *列表被拆分为具有＜code＞〔〕＜/code＞解引用器的属性键，用于
 *例如，YAML：
 *
 *<pre-class=“code”>
 *服务器：
 *-开发.bar.com
 *-foo.bar.com
 *</pre>
 *
 *变成这样的财产：
 *
 *<pre-class=“code”>
 *服务器[0]=dev.bar.com
 *服务器[1]=foo.bar.com
 *</pre>
 *
 *＜p＞自Spring Framework 5.0.6起，需要SnakeYAML 1.18或更高版本。
 *
 *@作者Dave Syer
 *@作者Stephane Nicoll
 *@作者Juergen Hoeller
 *@自4.1
 */
public class YamlPropertiesFactoryBean extends YamlProcessor implements FactoryBean<Properties>, InitializingBean {

	private boolean singleton = true;

	@Nullable
	private Properties properties;


	/**
	 * Set if a singleton should be created, or a new object on each request
	 * otherwise. Default is {@code true} (a singleton).
	 */
	/**
	 *设置是否应创建单例，或在每个请求上创建新对象
	 *否则。默认值为｛@code true｝（单例）。
	 */
	public void setSingleton(boolean singleton) {
		this.singleton = singleton;
	}

	@Override
	public boolean isSingleton() {
		return this.singleton;
	}

	@Override
	public void afterPropertiesSet() {
		if (isSingleton()) {
			this.properties = createProperties();
		}
	}

	@Override
	@Nullable
	public Properties getObject() {
		return (this.properties != null ? this.properties : createProperties());
	}

	@Override
	public Class<?> getObjectType() {
		return Properties.class;
	}


	/**
	 * Template method that subclasses may override to construct the object
	 * returned by this factory. The default implementation returns a
	 * properties with the content of all resources.
	 * <p>Invoked lazily the first time {@link #getObject()} is invoked in
	 * case of a shared singleton; else, on each {@link #getObject()} call.
	 * @return the object returned by this factory
	 * @see #process(MatchCallback)
	 */
	/**
	 *子类可以重写以构造对象的模板方法
	 *这家工厂退回的。默认实现返回
	 *包含所有资源内容的财产。
	 *＜p＞在中首次调用｛@link#getObject（）｝时延迟调用
	 *共享单例的情况；否则，在每个｛@link#getObject（）｝调用上执行。
	 *@return此工厂返回的对象
	 *@参见#process（MatchCallback）
	 */
	protected Properties createProperties() {
		Properties result = CollectionFactory.createStringAdaptingProperties();
		process((properties, map) -> result.putAll(properties));
		return result;
	}

}
